home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
DS-CD ROM 2 1993 August
/
DS CD-ROM 2.Ausgabe (August 1993).iso
/
programm
/
ds0257
/
util.exe
/
MAKEDOC.DOC
< prev
next >
Wrap
Text File
|
1992-02-23
|
22KB
|
721 lines
MAKEDOC.COM V1.20
Erstellen der Dokumentation zu Assembler-Programmen
(c) Copyright by
Bernd Schemmer
Ondrup 117
4710 Lüdinghausen 2
Letzter Update: 23.02.1992
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 1
Inhalt Seite
────────────────────────────────────────────────────────────
System-Vorraussetzungen ................................ 2
Vertrieb von MakeDoc ................................... 2
Beschreibung ........................................... 2
Aufruf ................................................. 4
Benutzung der Environment-Variable MAKEDOC ............. 10
Kommentare in den Parametern und in der
Environment-Variable ................................... 10
Errorlevel ............................................. 11
Interna ................................................ 11
────────────────────────────────────────────────────────────────────────────────
Inhalts-Verzeichnis I 1
System-Vorraussetzungen
───────────────────────
Die Systemvorrausetzung für die Nutzung von MAKEDOC.COM sind minimal:
Nur ein IBM-PC/AT/Kompatibler mit dem Betriebssystem MS-DOS 3+ wird
benötigt.
MAKEDOC wurde für die Bearbeitung von Quelltexten des A86 geschrieben
- d.h. das Programm kennt nur die dem A86 bekannten Schlüsselwörter.
Es sollte aber möglich sein, Quelltexte für andere Assembler so zu
korrigieren, daß MAKEDOC für diese ebenfalls verwendet werden kann.
Ausnahme:
Die Syntax von Macros und Anweisungen zur bedingten Assemblierung
sind A86 spezifisch.
Vertrieb von MakeDoc
────────────────────
MAKEDOC.COM ist Teil der Sammlung Lib4A86 und wird als Shareware
vertrieben. Für die Bedingungen zur Benutzung und Weitergabe von
MAKEDOC.COM deshalb bitte in der Dokumentation zu Lib4A86 nachsehen.
Beschreibung
────────────
MAKEDOC erstellt die Dokumentation eines Assembler-Quelltextes durch
Extraktion von bestimmten Kommentaren und Teilen des Quelltextes aus
diesem. D.h. durch ausführliche Kommentare im Quelltext können die
Dokumentation und der Quelltext gleichzeitig erstellt werden.
Die Länge des Quelltextes unterliegt dabei keinerlei Einschränkungen.
MAKEDOC arbeitet mit Zeilen mit max. 255 Zeichen Länge. Der Quelltext
muß im ASCII-Format (so wie ihn auch der Assembler haben will) vor-
liegen.
In die Ausgabedatei werden folgende Zeilen der Eingabedatei über-
nommen (Jeweils mit #N führenden Leerzeichen versehen, Voreinstellung
für #N ist 2):
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 2
- Alle Zeilen die mit einem einzelnen Semikolon in der ersten Spalte
beginnen, wobei das Semikolon mit einem Leerzeichen überschrieben
wird. Kommentare, die nicht übernommen werden sollen müssen z.B.
mit zwei Semikolon gekennzeichnet werden.
- Alle Zeilen, in denen eine A86-Direktive in Großbuchstaben steht.
(Gilt auch für Direktiven, die nur aus nicht alphabetischen Zeichen
bestehen, z.B. die Direktive .287) Die MAKEDOC bekannten Direktiven
können über den Parameter 'S1' ermittelt werden. Direktiven die
nicht übernommen werden sollen, können z.B. in Kleinbuchstaben ge-
schrieben werden.
Besonderheiten hierbei:
STRUC und SEGMENT-Blöcke werden expandiert wobei jeweils #M Leer-
zeichen vor jeder Zeile zusätzlich eingefügt werden. (Voreinst. für
#M ist 3)
MACRO-Definitionen und Blöcke zwischen Direktiven zur bedingten
Assemblierung (#IF, #ELSEIF und #ENDIF), werden vollständig über-
nommen (jeweils mit #M führenden Leerzeichen).
Hinweis: Falls einzelne Blöcke des Quellcodes übernommen werden
sollen, können diese durch eine (eigentlich überflüssige
aber unschädliche) Klammerung gekennzeichnet werden, z.B.:
; ... Anweisungen, die nicht übernommen werden sollen
#IF TRUE
; ... Anweisungen, die übernommen werden sollen
#ENDIF
; ... Anweisungen, die nicht übernommen werden sollen
Die Schlüsselwörter für Klammerungen sollten immer in der
gleichen Schreibweise angegeben werden!
MAKEDOC.COM schließt am Ende jeder Datei alle offenen Klammerungen
(z.B. #IF ... #ENDIF, MACRO ... #EM, etc) und gibt, falls noch eine
oder mehrere Klammerungen auf sind, eine Warnung auf die Standard-
Ausgabe aus.
- Zeilen, die mit mindestens 4 Leerzeichen beginnen und Zeilen, die
mit 2 Semikolon (';;') beginnen werden nur in Blöcken übernommen.
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 3
- Die Zeile mit dem Inhalt
; ***** END OF PUBLIC *****
wird als Ende des zu dokumentierenden Teils der Datei angesehen.
(d.h. alle folgenden Zeilen werden ignoriert; die Schreibweise und
das Format der Zeile ist signifikant)
- Alle Zeilen zwischen den Zeilen
; ***** MAKEDOC OFF
und
; ***** MAKEDOC ON
werden NICHT übernommen (auch nicht in Blöcken; die Schreibweise
und das Format sind signifikant.)
Die Zeile '; ***** MAKEDOC ON' wird von MAKEDOC bei jeder neuen
Datei implizit als erste Zeile angenommen.
- Alle mit der Zeichenfolge
; *****
(hinter den fünf Sternen muß mindestens ein Leerzeichen folgen)
beginnenden Zeilen werden NICHT übernommen. (Die Schreibweise und
das Format sind signifikant.)
- Jeder Output-Datei wird ein Datei-Header vorangestellt.
Aufruf
──────
MAKEDOC wird folgendermaßen aufgerufen:
MAKEDOC [{path}sourcefile-maske] {{path}{outputfile}} {switches}
oder
MAKEDOC -?
zur Ausgabe eines Hilfstextes
Die Reihenfolge der Parameter muß eingehalten werden. Die Parameter
{path}outputfile und Switches sind optional, d.h. beide können
angegeben oder weggelassen werden.
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 4
Der Parameter sourcefile-maske kann ein Dateiname oder eine Maske mit
Jokern (* oder ?) sein (jeweils optional incl. einem Pfad).
Das Programm bearbeitet dann entweder nur die angegebene Datei oder
alle unter die Maske fallenden Dateien sequentiell in der Reihenfolge
in der sie im Directory stehen.
Der Parameter outputfile kann entweder ein Pfad (abgeschlossen mit
'\' oder ':') oder ein Dateiname (mit oder ohne Pfad) sein. Masken
sind für diesen Parameter nicht möglich.
Wird hier ein Pfad angegeben, so erstellt das Programm automatisch
für jede Eingabedatei den Namen der Ausgabe-Datei aus dem hier ange-
gebenen Pfad plus dem Namen der Eingabe-Datei versehen mit der vor-
eingestellten Extension .DOC.
Bei Angabe eines Dateinamens wird diese, falls als sourcefile-maske
ein Dateiname angegeben ist, als Ausgabedatei genommen. Ist in diesem
Fall als sourcefile-maske eine Maske angegeben, so wird der Schalter
'A1' (s.u.) implizit vom Programm gesetzt, d.h. die Ausgaben für alle
unter die Maske fallenden Dateien werden sequentiell in die Datei
geschrieben.
Falls der Parameter outputfile nicht angegeben wird, so werden die
Ausgabedatei(en) in dem Directory, in dem die Quelldatei(en) stehen
erstellt.
Der Parameter switches steht für verschiedene mögliche Schalter über
die MAKEDOC gesteuert werden kann.
Die Schalter können in Groß- oder Kleinbuchstaben und in beliebiger
Reihenfolge und Kombination angegeben werden. Die Schalter werden
sequentiell von links nach rechts bearbeitet. Ein falscher Schalter
führt zum Programmabbruch. Bei Angabe von mehreren gleichen Schaltern
mit unterschiedlichen Werten oder mehreren sich ausschliessenden
Schaltern wird nur der zuletzt angegebene berücksichtigt.Die Schalter
können einzeln (z.B. '-A -D -X.ext -O2') oder zusammengesetzt (z.B.
'-ADX.extO2') angegeben werden.
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 5
Mögliche Schalter:
-Inn - Explizite Angabe von #N
-> Anzahl der normalerweise einzufügenden Leerzeichen
(dez., Voreinst.: 2, Intervall: 0..255)
-Enn - Explizite Angabe von #M
-> Anzahl der bei der Expansion von STRUC-, SEGMENT- und
MACRO-Blöcken einzufügenden Leerzeichen
(dez., Voreinst.: 3, Intervall: 0..255)
-L{nn} - Anzahl der Zeilen pro Seite für die Ausgabedatei bestimmen
(dez., Voreinst: 0, Intervall: 0, 20..255, 0 bedeutet keine
Seitenformatierung vornehmen, Voreinstellung für nn, falls
der Schalter in der Form '-L' angegeben ist, ist 60)
Ein Wert kleiner als 20 wird von MAKEDOC auf 20 gesetzt.
Falls kein Wert hinter 'L' angegeben werden soll, muß der
Schalter einzeln angegeben werden.
(z.B. '-L -N' aber NICHT '-LN' !)
Formfeeds in der Eingabedatei werden von MAKEDOC berück-
sichtigt, falls sie in einer Zeile stehen, die von MAKEDOC
in die Ausgabedatei übernommen wird (z.B. ein durch ein
Semikolon eingeleiteter Kommentar).
Bei mehreren Eingabedateien wird von MAKEDDOC die Ausgabe
für jede neue Eingabedatei auf einem neuen Blatt begonnen.
-S{n} - n = 1 ->> Nur Anzeige der dem Programm bekannten Direktiven
(Voreinstellung für n)
n = 0 ->> ignoriere den Schalter 'S1' falls er gesetzt ist
Für die Angabe dieses Schalters muß als erster Parameter
eine bestehende Datei bzw. ein existierendes Zeichenorien-
tiertes Gerät angegeben werden. Diese(s) wird aber nicht
bearbeitet.
Beispiel: MAKEDOC NUL -S
-N{n} - n = 1 ->> Datei-Header nicht schreiben (Voreinst. für n)
n = 0 ->> Datei-Header schreiben (Voreinstellung)
-P{n} - n = 1 ->> Vollständigen Namen incl. Pfad in den Datei-Header
übernehmen (Voreinstellung für n)
n = 0 ->> Nur den Namen in den Header übernehmen (Voreinst.)
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 6
-!{n} - n = 1 ->> auch die internen Routinen bearbeiten (d.h. Igno-
rieren der Zeile '; ***** END OF PUBLIC *****')
(Voreinstellung für n)
n = 0 ->> internen Routinen nicht bearbeiten (Voreinst.)
-A{n} - n = 1 ->> Falls eine Ausgabedatei schon besteht wird sie
verlängert (Voreinstellung für n)
n = 0 ->> Bestehende Ausgabe-Dateien werden überschrieben
(Voreinst.)
-On - n = 0 ->> Die Existenz der Ausgabedateien ist ohne
Bedeutung. (Voreinstellung)
n = 1 ->> Bearbeite nur Dateien, von denen die Ausgabedatei
noch NICHT existiert.
Dieser Schalter ist z.B. sinnvoll, falls bei einen vorherigen
Programmlauf als erster Parameter eine Maske angegeben wurde,
und die Ausführung des Programms nach der Bearbeitung von
einigen aber nicht allen unter die Maske fallenden Programmen
durch einen Fehler abgebrochen wurde. In diesem Fall kann
nach der Beseitigung des Fehlers das Programm noch mal mit
den gleichen Parametern und dem Schalter 'O1' aufgerufen
werden. Es erstellt dann nur noch die fehlenden Dateien.
n = 2 ->> Bearbeite nur Dateien, von denen die Ausgabedatei
SCHON existiert. Dieser Schalter kann z.B. zum
Updaten von bestehenden Dateien benutzt werden.
n = 3 ->> Vor der Bearbeitung jeder Datei kann der Benutzer
entscheiden, ob diese bearbeitet werden soll.
n = 4 ->> In diesem Fall fragt das Programm den Benutzer
nur falls die Ausgabe-Datei schon existiert; alle
anderen Dateien werden ohne Nachfrage bearbeitet.
-Z{n} - n = 1 ->> MAKEDOC arbeitet mit CTRL-Z als Dateiende-Markie-
rungen (Voreinstellung für n)
n = 0 ->> MAKEDOC arbeitet NICHT mit Dateiende-Markierungen
(Voreinst.)
-D{n} - n = 1 ->> Unterdrücken der Laufzeitanzeige
(Voreinstellung für n)
n = 0 ->> Laufzeitanzeige ausgeben (Voreinst.)
In diesem Fall gibt MAKEDOC für jede geschriebene
Zeile das Zeichen '√' und für jede nur gelesene
aber nicht geschriebene Zeile das Zeichen '.'
aus.
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 7
-X.aaa
- Mit diesem Schalter kann die voreingestellte Extension für
die Ausgabedatei geändert werden. (.aaa = neue Extension)
Der Punkt muß angegeben werden. Die neue Extension kann
bis zu 3 Zeichen lang sein. Soll(en) die Ausgabedatei(en)
keine Extension erhalten, so muß der Schalter in der Form
'X.' angegeben werden. Falls die neue Extension weniger
als 4 Zeichen (incl. Punkt) lang ist, muß sie am Ende
eines Parameters stehen.
Beispiel:
Die neue Extension soll '.9' und der Schalter 'D' soll auf
1 gesetzt werden.
Die Parameter hierfür müssen dann lauten:
'-dx.9' oder '-x.9 -d'
Falsch ist
'.X.9d'
(In diesem Fall würde MAKEDOC die neue Extension auf '.9d'
setzen.)
Hinweis:
Die hier angegebene Extension wird nur benutzt, falls keine
Ausgabedatei angegeben ist oder für die Ausgabedatei nur
ein Pfad angegeben ist.
Hinweise zur Schreibweise:
- Angaben in geschweiften Klammern {} sind optional
- n ->> 0 oder 1 (bei dem Schalter 'o' auch 2, 3 oder 4)
- nn ->> dezimaler Wert
- (Voreinst. für n) oder (Voreinstellung für n)
->> Falls der Schalter ohne Wert angegeben ist, so wird dieser
Wert vom Programm für den Schalter genommen.
- (Voreinstellung) oder (Voreinst.)
->> Falls der Schalter nicht angegeben ist, so wird dieser Wert
vom Programm angenommen.
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 8
Beispiele:
MAKEDOC *.8 -o0 -x.DOC -i02 -e03 -l0 -s0 -n0 -p0 -!0 -a0 -z0 -d0
-> Aufruf von MAKEDOC mit den Voreinstellungen, dieser Aufruf ist
also äquvialent mit
MAKEDOC *.8
MAKEDOC *.8 acht.doc
-> Bearbeite alle Dateien mit der Extension '.8' und schreibe die
Ausgaben in die Datei 'ACHT.DOC'. Der Schalter 'A1' wird vom Pro-
gramm implizit gesetzt, da mehrere Quelldateien aber nur eine Aus-
gabedatei angegeben ist.
MAKEDOC *.8 C:\doc\ -DO4
-> Bearbeite alle Dateien mit der Extension '.8' und schreibe die
Ausgaben jeweils in eine Datei mit gleichem Namen und der Exten-
sion '.DOC' im Directory 'C:\doc\'. Unterdrücke die Laufzeit-
Anzeige und frage den Benutzer, falls eine Ausgabe-Datei schon
existiert.
MAKEDOC *.8 -o1
-> Bearbeite alle Dateien mit der Extension '.8', von denen im akt.
Directory noch keine Ausgabe-Datei mit der Extension '.DOC'
existiert.
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 9
Benutzung der Environment-Variable MAKEDOC
──────────────────────────────────────────
Alle Schalter können auch in der Environment-Variable MAKEDOC
gesichert werden. Der Inhalt dieser Variable wird vor den in den
Parametern angegebenen Schaltern bearbeitet, so daß die in der
Environment-Variable gespeicherten Schalter durch die Schalter in
der Aufrufzeile überschrieben werden können. Die Environment-
Variable darf keine Leerzeichen oder Tabulatoren enthalten. In der
Environment-Variable können keine Ein- oder Ausgabedateien angegeben
werden.
Beispiele:
SET MAKEDOC=-do3
-> Bei allen folgenden Aufrufen von MAKEDOC den Schalter 'D' auf 1
und den Schalter 'O' auf 3 setzen, falls in den Parametern nichts
anderes angegeben ist.
SET MAKEDOC=-al
-> Der Schalter 'L' ohne Wert muß in der Environment-Variable immer
als letzter angegeben werden!
Kommentare in den Parametern und in der Environment-Variable
────────────────────────────────────────────────────────────
MAKEDOC erlaubt es hinter den Parametern noch einen Kommentar anzu-
geben. Dieser muß mit dem Zeichen @ beginnen. Alle hinter diesem
Parameter folgenden Parameter werden von MAKEDOC überlesen. Sinnvoll
ist dies z.B. bei Aufruf von MAKEDOC aus Batch-Dateien.
Falls die Environment-Variable MAKEDOC als erstes Zeichen das Zeichen
@ enthält, wird diese von MAKEDOC nicht ausgewertet.
Beispiele:
MAKEDOC *.inc -o3ad @ -z Dies ist ein Kommentar!
-> Es werden nur die Parameter '*.inc -o3ad' ausgewertet
MAKEDOC *.inc -o3ad@ Dies ergibt einen Fehler!
-> Fehler, das Zeichen @ muß einen neuen Parameter einleiten!
SET MAKEDOC=@-d
-> Unterdrücken der Berücksichtigung der Environment-Variable MAKEDOC
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 10
Errorlevel
──────────
Als Errorlevel wird 0 zurückgegeben, falls kein Fehler auftrat.
Im Fehlerfall werden folgende Errorlevel zurückgegeben:
Fehler │ Errorlevel
──────────────────────────────────────┼──────────────
Falscher/Fehlender Parameter │ 1
Falscher Schalter angegeben │ 2
Quelldatei = Zieldatei │ 3
Fehler beim Öffnen der Quelldatei │ 4
Fehler beim Öffnen der Zieldatei │ 5
Fehler beim Lesen der Quelldatei │ 6
Fehler beim Schreiben der Zieldatei │ 7
Fehler beim Schliessen der Quelldatei │ 8
Fehler beim Schliessen der Zieldatei │ 9
Keine Datei gefunden │ 10
Hardware-Fehler │ 11
Fehler in der Speicherverwaltung │ 12
Unbekannter Fehler │ 13
Interna
───────
Für die Dateibearbeitung wird jeweils für die Ein- und Ausgabe-Datei
ein Puffer von max. 65.520 Byte allokiert (falls möglich). Die mini-
male Größe für jeden Puffer beträgt 1024 Byte. Falls kein freier
Speicher für die Puffer vorhanden ist, wird das Programm nach der
Ausgabe einer Fehlermeldung abgebrochen.
Für jede zu bearbeitende Datei wird überprüft, ob die Namen der Ein-
und Ausgabedatei identisch sind und, falls dies so ist, das Programm
nach der Ausgabe einer Fehlermeldung abgebrochen.
Das Programm fängt alle Fehler (auch Hardware-Fehler) ab und bricht
in diesem Fall die Ausführung nach der Ausgabe einer Fehlermeldung
ab. Die evtl. schon teilweise geschriebene(n) Ausgabedatei(en)
werden nach dem Auftritt eines Fehlers nicht gelöscht.
Alle Ausgaben des Programms (mit Ausnahme der Laufzeit-Anzeige, s.u.)
erfolgen über das DOS und sind somit in eine Datei umlenkbar.
Die Laufzeit-Anzeige wird aus Geschwindigkeitsgründen direkt über den
Interrupt 29h ausgegeben. Falls die Ausgabe des Programms nicht auf
die Standard-Ausgabe geht, wird die Laufzeit-Anzeige nicht angezeigt.
ACHTUNG: Das Programm benutzt die undokumentierte Funktion 60h des
Interrupt 21h und den nur teilweise dokumentierten Inter-
rupt 29h!
────────────────────────────────────────────────────────────────────────────────
Dokumentation für MakeDoc Seite 11